/**
 * 数据格式化工具模块
 * 
 * 本模块提供了一系列用于格式化数据的实用函数，包括：
 * - 日期时间格式化
 * - 文件大小格式化
 * - 金额格式化
 * 
 * 这些工具函数可在整个应用程序中复用，确保数据呈现的一致性和可读性。
 * 所有函数都设计为纯函数，不会修改输入参数，并返回格式化后的字符串。
 * 
 * @module utils/format
 */
import dayjs from 'dayjs'; // 引入dayjs库用于日期处理

/**
 * 格式化日期时间
 * 将日期对象或日期字符串转换为指定格式的日期时间字符串
 * 
 * @param date 日期对象或日期字符串
 * @param format 格式化模式，默认为'YYYY-MM-DD HH:mm:ss'
 * @returns 格式化后的日期时间字符串，如果输入为空则返回'-'
 */
export const formatDateTime = (date: string | Date | undefined, format: string = 'YYYY-MM-DD HH:mm:ss'): string => {
  if (!date) {
    return '-'; // 如果日期为空，返回占位符
  }
  return dayjs(date).format(format); // 使用dayjs格式化日期
};

/**
 * 格式化日期（只显示年月日）
 * 是formatDateTime的便捷封装，默认只显示年月日部分
 * 
 * @param date 日期对象或日期字符串
 * @param format 格式化模式，默认为'YYYY-MM-DD'
 * @returns 格式化后的日期字符串
 */
export const formatDate = (date: string | Date | undefined, format: string = 'YYYY-MM-DD'): string => {
  return formatDateTime(date, format); // 复用formatDateTime函数，使用不同的默认格式
};

/**
 * 格式化时间（只显示时分秒）
 * 是formatDateTime的便捷封装，只显示时间部分
 * 
 * @param date 日期对象或日期字符串
 * @returns 格式化后的时间字符串，格式为'HH:mm:ss'
 */
export const formatTime = (date: string | Date | undefined): string => {
  return formatDateTime(date, 'HH:mm:ss'); // 复用formatDateTime函数，固定使用时间格式
};

/**
 * 格式化文件大小
 * 将字节数转换为人类可读的文件大小表示形式（B, KB, MB, GB等）
 * 
 * @param bytes 字节数
 * @returns 格式化后的文件大小字符串，如"1.5 MB"
 */
export const formatFileSize = (bytes: number | undefined): string => {
  if (bytes === undefined || bytes === null) return '-'; // 处理空值
  if (bytes === 0) return '0 B'; // 处理0字节的情况
  
  const units = ['B', 'KB', 'MB', 'GB', 'TB', 'PB']; // 文件大小单位数组
  const i = Math.floor(Math.log(bytes) / Math.log(1024)); // 计算应使用的单位索引
  
  return parseFloat((bytes / Math.pow(1024, i)).toFixed(2)) + ' ' + units[i]; // 格式化结果并添加单位
};

/**
 * 格式化金额（添加千位分隔符）
 * 将数字格式化为带千位分隔符的金额表示形式
 * 
 * @param amount 金额
 * @param decimalPlaces 小数位数，默认为2
 * @returns 格式化后的金额字符串，如"1,234.56"
 */
export const formatAmount = (amount: number | undefined, decimalPlaces: number = 2): string => {
  if (amount === undefined || amount === null) return '-'; // 处理空值
  
  return amount.toLocaleString('zh-CN', { // 使用中文区域设置格式化金额
    minimumFractionDigits: decimalPlaces, // 最小小数位数
    maximumFractionDigits: decimalPlaces  // 最大小数位数
  });
};

// 默认导出所有格式化函数，方便一次性引入
export default {
  formatDate,
  formatDateTime,
  formatTime,
  formatFileSize,
  formatAmount
}; 